---
redirect_from:
  - /rest-api
---

# REST API reference

[REST API][ref-rest-api] provides the following endpoints.

## `/v1/load`

Get the data for a query.

| Parameter   | Description                                                                                                           |
| ----------- | --------------------------------------------------------------------------------------------------------------------- |
| `query`     | Either a single URL encoded Cube [Query](/product/apis-integrations/rest-api/query-format), or an array of queries    |
| `queryType` | If multiple queries are passed in `query` for [data blending][ref-recipes-data-blending], this must be set to `multi` |

Response

- `query` - The query passed via params. It can be an array of queries and in
  such case it will be treated as a [Data Blending][ref-recipes-data-blending]
  query.
- `data` - Formatted dataset of query results.
- `annotation` - Metadata for query. Contains descriptions for all query items.
  - `title` - Human readable title from the data model.
  - `shortTitle` - Short title for visualization usage (ex. chart overlay)
  - `type` - Data type
- `total` - The total number of rows returned for the query. Useful for
  paginating results.

Example request:

```bash{outputLines: 1,3-9,11-15}
# Request with http method GET
curl \
  -H "Authorization: EXAMPLE-API-TOKEN" \
  -G \
  --data-urlencode 'query={"measures":["users.count"]}' \
  http://localhost:4000/cubejs-api/v1/load

# Request with http method POST
# Use POST to fix problem with query length limits
curl \
 -X POST  \
 -H "Content-Type: application/json" \
 -H "Authorization: EXAMPLE-API-TOKEN" \
 --data '{"query": {"measures":["users.count"]}}' \
 http://localhost:4000/cubejs-api/v1/load
```

Example response:

```json
{
  "query": {
    "measures": ["users.count"],
    "filters": [],
    "timezone": "UTC",
    "dimensions": [],
    "timeDimensions": []
  },
  "data": [
    {
      "users.count": "700"
    }
  ],
  "annotation": {
    "measures": {
      "users.count": {
        "title": "Users Count",
        "shortTitle": "Count",
        "type": "number"
      }
    },
    "dimensions": {},
    "segments": {},
    "timeDimensions": {}
  }
}
```

<WarningBox>

Currently all fetched numericals are returned in the same format as driver
returns it without any additional processing. Most of drivers return numerical
values as strings instead of javascript integer or float to ensure there's no
loss of significance. Client code should take care of parsing such numerical
values.

</WarningBox>

## `/v1/sql`

Get the SQL Code generated by Cube to be executed in the database.

| Parameter | Description                                                               |
| --------- | ------------------------------------------------------------------------- |
| query     | URLencoded Cube [Query](/product/apis-integrations/rest-api/query-format) |

Response

- `sql` - JSON Object with the following properties
  - `sql` - Formatted SQL query with parameters
  - `order` - Order fields and direction used in SQL query
  - `cacheKeyQueries` - Key names and TTL of Cube data cache
  - `preAggregations` - SQL queries used to build pre-aggregation tables

Example request:

```bash{outputLines: 2-6}
curl \
  -H "Authorization: EXAMPLE-API-TOKEN" \
  -G \
  --data-urlencode 'query={"measures":["users.count"],
  "timeDimensions":[{"dimension": "users.createdAt","granularity":"day","dateRange":["2019-03-01","2019-03-31"]}]}' \
  http://localhost:4000/cubejs-api/v1/sql
```

Example response:

```json
{
  "sql": {
    "sql": [
      "SELECT\n      date_trunc('day', (users.created_at::timestamptz AT TIME ZONE 'UTC')) \"users.created_at_date\", count(users.id) \"users.count\"\n    FROM\n      public.users AS users\n  WHERE (users.created_at >= $1::timestamptz AND users.created_at <= $2::timestamptz) GROUP BY 1 ORDER BY 1 ASC LIMIT 10000",
      ["2019-03-01T00:00:00Z", "2019-03-31T23:59:59Z"]
    ],
    "timeDimensionAlias": "users.created_at_date",
    "timeDimensionField": "users.createdAt",
    "order": [
      {
        "id": "users.createdAt",
        "desc": false
      }
    ],
    "cacheKeyQueries": {
      "queries": [
        ["select max(users.created_at) from public.users AS users", []]
      ],
      "renewalThreshold": 21600
    },
    "preAggregations": []
  }
}
```

## `/v1/meta`

Get meta-information for cubes and views defined in the data model. Information about cubes and views with `public: false` will not be returned.

Response

- `cubes` - Array of cubes and views
  - `name` - Codename of the cube/view
  - `type` - Type can be "cube" or "view"
  - `title` - Human-readable cube/view name
  - `meta` - Custom metadata
  - `measures` - Array of measures in this cube/view
  - `dimensions` - Array of dimensions in this cube/view
  - `segments` - Array of segments in this cube/view
  - `connectedComponent` - An integer representing a join relationship. If the same value is returned for two cubes, then there is
    at least one join path between them.

Example request:

```bash{outputLines: 2-4}
curl \
  -H "Authorization: EXAMPLE-API-TOKEN" \
  -G \
  http://localhost:4000/cubejs-api/v1/meta
```

Example response:

```json
{
  "cubes": [
    {
      "name": "Users",
      "title": "Users",
      "meta": {
          "someKey": "someValue",
          "nested": {
            "someKey": "someValue"
          }
      },
      "connectedComponent": 1,
      "measures": [
        {
          "name": "users.count",
          "title": "Users Count",
          "shortTitle": "Count",
          "aliasName": "users.count",
          "type": "number",
          "aggType": "count",
          "drillMembers": ["users.id", "users.city", "users.createdAt"]
        }
      ],
      "dimensions": [
        {
          "name": "users.city",
          "title": "Users City",
          "type": "string",
          "aliasName": "users.city",
          "shortTitle": "City",
          "suggestFilterValues": true
        }
      ],
      "segments": []
    }
  ]
}
```

## `/v1/pre-aggregations/jobs`

Trigger pre-aggregation build jobs or retrieve statuses of such jobs.

### Triggering jobs

| Parameter                  | Description                                                    | Required |
| -------------------------- | -------------------------------------------------------------- | -------- |
| `action`                   | Use `post` to trigger jobs                                     | ✅       |
| `selector.contexts`        | Array of objects, each containing a `securityContext`          | ✅       |
| `selector.timezones`       | Array of timezones                                             | ✅       |
| `selector.datasources`     | Array of data source names which have pre-aggregations defined | ❌       |
| `selector.cubes`           | Array of cube names which contain pre-aggregations             | ❌       |
| `selector.preAggregations` | Array of pre-aggregation names                                 | ❌       |

To trigger pre-aggregation builds, send a `POST` request with a payload
including `post` as the `action` and `selector` properties. The response will
contain an array of `tokens` (identifiers) of triggered jobs.

Example request triggering builds of all pre-aggregations defined in all cubes
using an empty security context and a `UTC` timezone:

```bash{outputLines: 2-12}
curl \
  -d '{
    "action": "post",
    "selector": {
      "contexts": [{ "securityContext": {} }],
      "timezones": ["UTC"]
    }
  }' \
  -H "Authorization: EXAMPLE-API-TOKEN" \
  -H "Content-Type: application/json" \
  -X POST \
  https://localhost:4000/cubejs-api/v1/pre-aggregations/jobs
```

Example request triggering builds of all pre-aggregations defined in the
`orders` cube using an empty security context and a `UTC` timezone:

```bash{outputLines: 2-13}
curl \
  -d '{
    "action": "post",
    "selector": {
      "contexts": [{ "securityContext": {} }],
      "timezones": ["UTC"],
      "cubes": ["orders"]
    }
  }' \
  -H "Authorization: EXAMPLE-API-TOKEN" \
  -H "Content-Type: application/json" \
  -X POST \
  https://localhost:4000/cubejs-api/v1/pre-aggregations/jobs
```

Example request triggering builds of the `main` pre-aggregation defined in the
`orders` cube using an empty security context and a `UTC` timezone:

```bash{outputLines: 2-13}
curl \
  -d '{
    "action": "post",
    "selector": {
      "contexts": [{ "securityContext": {} }],
      "timezones": ["UTC"],
      "preAggregations": ["orders.main"]
    }
  }' \
  -H "Authorization: EXAMPLE-API-TOKEN" \
  -H "Content-Type: application/json" \
  -X POST \
  https://localhost:4000/cubejs-api/v1/pre-aggregations/jobs
```

Example response:

```json
[
  "e9a6a0c55885cea5371348500ce7d7dc",
  "d1329b6c8d152e734fc4dcf7307b1b58",
  "6f4ea38373663fffc4334a576574845b",
  "ea903b10634b2f3141b35a2529870e89"
]
```

### Retrieving statuses of jobs

| Parameter | Description                                                       | Required |
| --------- | ----------------------------------------------------------------- | -------- |
| `action`  | Use `get` to retrieve statuses of previously triggered jobs       | ✅       |
| `tokens`  | Array of `tokens` returned when triggering jobs                   | ✅       |
| `resType` | Use `object` to get a JSON object instead of an array in response | ❌       |

To retrieve statuses of previously triggered jobs, send a `POST` request with a
payload including the `tokens` property.

Example request:

```bash{outputLines: 2-14}
curl \
  -d '{
    "action": "get",
    "tokens": [
      "e9a6a0c55885cea5371348500ce7d7dc",
      "d1329b6c8d152e734fc4dcf7307b1b58",
      "6f4ea38373663fffc4334a576574845b",
      "ea903b10634b2f3141b35a2529870e89"
    ]
  }' \
  -H "Authorization: EXAMPLE-API-TOKEN" \
  -H "Content-Type: application/json" \
  -X POST \
  https://localhost:4000/cubejs-api/v1/pre-aggregations/jobs
```

Example response:

```json
[
  {
    "token": "e9a6a0c55885cea5371348500ce7d7dc",
    "table": "prod_pre_aggregations.orders_category_and_date_hod0x3hf_03krd5ns_1hop3hn",
    "status": "processing",
    "selector": {
      "cubes": ["orders"],
      "preAggregations": ["orders.category_and_date"],
      "contexts": [{ "securityContext": { "tenant": "tenant_1" } }],
      "timezones": ["UTC"],
      "dataSources": ["default"]
    }
  },
  {
    "token": "d1329b6c8d152e734fc4dcf7307b1b58",
    "table": "prod_pre_aggregations.orders_category_and_date_mzfp445f_r2h2isa5_1hop3hn",
    "status": "processing",
    "selector": {
      "cubes": ["orders"],
      "preAggregations": ["orders.category_and_date"],
      "contexts": [{ "securityContext": { "tenant": "tenant_1" } }],
      "timezones": ["UTC"],
      "dataSources": ["default"]
    }
  },
  {
    "token": "6f4ea38373663fffc4334a576574845b",
    "table": "prod_pre_aggregations.orders_category_and_date_hod0x3hf_03krd5ns_1hop3hn",
    "status": "missing_partition",
    "selector": {
      "cubes": ["orders"],
      "preAggregations": ["orders.category_and_date"],
      "contexts": [{ "securityContext": { "tenant": "tenant_1" } }],
      "timezones": ["UTC"],
      "dataSources": ["default"]
    }
  },
  {
    "token": "ea903b10634b2f3141b35a2529870e89",
    "table": "prod_pre_aggregations.orders_category_and_date_mzfp445f_r2h2isa5_1hop3hn",
    "status": "missing_partition",
    "selector": {
      "cubes": ["orders"],
      "preAggregations": ["orders.category_and_date"],
      "contexts": [{ "securityContext": { "tenant": "tenant_1" } }],
      "timezones": ["UTC"],
      "dataSources": ["default"]
    }
  }
]
```

## `/readyz`

Returns the ready state of the deployment.

**Single-tenant:** Ensures the orchestration layer is operational and tests the
connection to the default `dataSource`.

**Multi-tenant:** Tests connections per-tenant. If no connections exist, it will
report as successful.

Example of a successful request:

```bash{outputLines: 2-12}
curl -i http://localhost:4000/readyz
HTTP/1.1 200 OK
X-Powered-By: Express
Access-Control-Allow-Origin: *
Content-Type: application/json; charset=utf-8
Content-Length: 19
ETag: W/"13-MyluqxoYxC0tUxBeZCnbaWYVLhg"
Date: Mon, 18 Jan 2021 15:39:57 GMT
Connection: keep-alive
Keep-Alive: timeout=5

{"health":"HEALTH"}
```

Example of a failed response:

```bash{outputLines: 2-12}
curl -i http://localhost:4000/readyz
HTTP/1.1 500 Internal Server Error
X-Powered-By: Express
Access-Control-Allow-Origin: *
Content-Type: application/json; charset=utf-8
Content-Length: 19
ETag: W/"13-MyluqxoYxC0tUxBeZCnbaWYVLhg"
Date: Mon, 18 Jan 2021 15:39:57 GMT
Connection: keep-alive
Keep-Alive: timeout=5

{"health":"DOWN"}
```

## `/livez`

Returns the liveness state of the deployment. This is confirmed by testing any
existing connections to `dataSource`. If no connections exist, it will report as
successful.

Example of a successful response:

```bash{outputLines: 2-12}
curl -i http://localhost:4000/livez
HTTP/1.1 200 OK
X-Powered-By: Express
Access-Control-Allow-Origin: *
Content-Type: application/json; charset=utf-8
Content-Length: 19
ETag: W/"13-MyluqxoYxC0tUxBeZCnbaWYVLhg"
Date: Mon, 18 Jan 2021 15:39:57 GMT
Connection: keep-alive
Keep-Alive: timeout=5

{"health":"HEALTH"}
```

Example of a failed response:

```bash{outputLines: 2-12}
curl -i http://localhost:4000/livez
HTTP/1.1 500 Internal Server Error
X-Powered-By: Express
Access-Control-Allow-Origin: *
Content-Type: application/json; charset=utf-8
Content-Length: 19
ETag: W/"13-MyluqxoYxC0tUxBeZCnbaWYVLhg"
Date: Mon, 18 Jan 2021 15:39:57 GMT
Connection: keep-alive
Keep-Alive: timeout=5

{"health":"DOWN"}
```

[ref-recipes-data-blending]:
  /product/data-modeling/concepts/data-blending#data-blending
[ref-rest-api]: /product/apis-integrations/rest-api
